/*-------------------------------------------------------------------------
 *
 * logtape.h
 *	  临时文件中的“逻辑磁带”管理。
 *
 * 请参阅 logtape.c 以获取解释。
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/utils/logtape.h
 *
 *-------------------------------------------------------------------------
 */

#ifndef LOGTAPE_H
#define LOGTAPE_H

#include "storage/sharedfileset.h"

/*
 * LogicalTapeSet 和 LogicalTape 是不透明类型，其细节在
 * logtape.c 之外是未知的。
 */
typedef struct LogicalTapeSet LogicalTapeSet;
typedef struct LogicalTape LogicalTape;


/*
 * tuplesort.c 对并行外部排序的处理方式是，工人，
 * 状态几乎与独立的串行排序相同，被迫
 * 在所有情况下生成最终材料化的排序输出带。这
 * 被冻结，就像任何需要最终材料化带的情况一样。
 * 然而，有一个不同之处，即冻结还将导出一个
 * 基础共享文件集 BufFile 以供共享。当这种情况发生时，冻结为工人生成
 * TapeShare 元数据，这通过共享内存传递给领导者。
 *
 * 然后，领导者进程可以将一组 TapeShare 元数据（每个
 * 工人参与者一个）传递给 LogicalTapeSetCreate()，以及一个
 * 共享文件集的句柄，这足以构造一个新的逻辑带集， 
 * 该带由工人材料化的每个带组成。
 *
 * 请注意，尽管 logtape.c 在带集结束时确实创建了一个空的领导者带，
 * 但由于共享缓冲区基础设施的限制，它永远无法被写入。
 */
typedef struct TapeShare
{
	/*
	 * 当前，所有领导者进程需要的只是材料化带的
	 * 第一个块的位置。
	 */
	long		firstblocknumber;
} TapeShare;

/*
 * logtape.c 中函数的原型
 */

extern LogicalTapeSet *LogicalTapeSetCreate(bool preallocate,
											SharedFileSet *fileset, int worker);
extern void LogicalTapeClose(LogicalTape *lt);
extern void LogicalTapeSetClose(LogicalTapeSet *lts);
extern LogicalTape *LogicalTapeCreate(LogicalTapeSet *lts);
extern LogicalTape *LogicalTapeImport(LogicalTapeSet *lts, int worker, TapeShare *shared);
extern void LogicalTapeSetForgetFreeSpace(LogicalTapeSet *lts);
extern size_t LogicalTapeRead(LogicalTape *lt, void *ptr, size_t size);
extern void LogicalTapeWrite(LogicalTape *lt, void *ptr, size_t size);
extern void LogicalTapeRewindForRead(LogicalTape *lt, size_t buffer_size);
extern void LogicalTapeFreeze(LogicalTape *lt, TapeShare *share);
extern size_t LogicalTapeBackspace(LogicalTape *lt, size_t size);
extern void LogicalTapeSeek(LogicalTape *lt, long blocknum, int offset);
extern void LogicalTapeTell(LogicalTape *lt, long *blocknum, int *offset);
extern long LogicalTapeSetBlocks(LogicalTapeSet *lts);

#endif							/* LOGTAPE_H */
